Skip to main content

Getting-Device-State

With OmniCore, you can control a device by modifying its configuration. A device configuration is an arbitrary, user-defined blob of data. After a configuration has been applied to a device, the device can report its state to OmniCore.

Device configuration works differently in the MQTT and HTTP bridges. See below for details.

For more information, see Devices, Configuration, and State.

Limits

Configuration updates are limited to 1 update per second, per device. However, for best results, device configuration should be updated much less often — at most, once every 10 seconds.

The update rate is calculated as the time between the most recent server acknowledgment and the next update request.

Reporting device state

MQTT

To report state to OmniCore through the MQTT bridge, publish messages to the /REGISTRY_ID/DEVICE_ID/state MQTT topic. You can select a Cloud Pub/Sub topic to store state events when you create or update a registry.

For more details, see Publishing over the MQTT bridge.

HTTP

To report state to OmniCore through the HTTP bridge, devices should use a setState request. The binary state data is passed in the body of the request as a base64-encoded string.

For more details, see Publishing over the HTTP bridge.

Getting device state data

This section explains how to get the state data that's reported to OmniCore by devices. (Devices themselves cannot read state data from the cloud.)

State data is returned in binary format. State data may have a different structure than the configuration data that triggers the state change.

For example, suppose you have a device with several fans. Your configuration data might be a JSON object containing a simple Boolean that enables or disables cooling:

Example of configuration data
{
'cooling': true
}

But the device's state data might include diagnostic information, as well as the fan data that you'd expect to see in response to a 'cooling' change:

Example of state data
{
'fan1_target_rpm': 1000,
'fan2_target_rpm': 1200,
'firmware_version': '1.2.3b'
}

The device's firmware_version is not related to the configuration data, but the device returns the full internal representation of its state. This example illustrates how device state can be useful for debugging in general, as well as for confirming that devices have acknowledged specific configurations.

You can get device state data using a Cloud Pub/Sub topic, Cloud Platform Console, the OmniCore API. Get Device States

OmniCore retains state data in storage. You can also configure an optional state notification Cloud Pub/Sub topic in each device registry, via Cloud console, or the API. This topic can be the same as or different from the telemetry event topic.

State data is published to Cloud Pub/Sub on a best-effort basis: if publication to the topic fails, it will not be retried. If no topic is defined, device state updates are still persisted internally by OmniCore, but only the last 10 states are retained.

Use the Device states list method to get the most recent device states (up to 10). Each Device resource has a DeviceState field that contains the state most recently received from the device. The DeviceRegistry resource has a StateNotificationConfig field that can be used to specify a state notification Cloud Pub/Sub topic when creating or updating a registry.